home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / PCTAGS15.ARJ / TAGS.DOC < prev    next >
Text File  |  1991-10-07  |  32KB  |  818 lines
  1.  
  2. ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  3. ▒┌                                                                          ┐▒
  4. ▒                          Tags Generator V1.5                               ▒
  5. ▒                                                                            ▒
  6. ▒            A TAGS generator for Assembly and C and written in C            ▒
  7. ▒                   V1.5 Dedicated to the Public Domain                      ▒
  8. ▒                                                                            ▒
  9. ▒                            October 7, 1991                                 ▒
  10. ▒                              J. Kercheval                                  ▒
  11. ▒                      [72450,3702] -- johnk@wrq.com                         ▒
  12. ▒└                                                                          ┘▒
  13. ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  14.  
  15. 10/07/91
  16.  
  17. This is V1.5
  18.  
  19. The moment you post something, you (or normally, someone else) finds
  20. a bug to let you know what a peon you really are.  V1.4 had problems
  21. with extended enumeration constants and syntactic vagaries regarding
  22. enum declarations.
  23.  
  24.                                     jbk
  25.  
  26. 10/04/91
  27.  
  28. This is V1.4
  29.  
  30. A bug was fixed in assembly tagging (local labels using ':' were
  31. being tagged when defines were enabled regardless of -al flag).
  32. Exclude file parsing (-x flag) was added.  Support for tagging of
  33. enumeration constants and internal static declarations (-ck -ci) was
  34. added.  Improved support of LISTFILES, now the list file may be in
  35. the form of a response file and filenames may be separated by '+',
  36. ',', ';' or whitespace (comments delimited by '#' are still
  37. supported).
  38.  
  39.                                     jbk
  40.  
  41. 10/01/91
  42.  
  43. This is V1.3
  44.  
  45. A bug was fixed in cleanup code executed on Ctrl-C, Break, file
  46. error, or memory allocation error.  In V1.2, one of these errors
  47. normally resulted in some lost chains in the file structure but only
  48. manifested on a failure condition.
  49.  
  50.                                     jbk
  51.  
  52. 9/30/91
  53.  
  54. This is V1.2
  55.  
  56. This code is dedicated to the Public Domain, this means you may use
  57. this code for any purpose and for any reason and without any
  58. warranty, suitability to task, etc.  Public Domain also means that
  59. you may not place your own Copyright on this code.  Do not claim it
  60. to be your work.  Portions of this are under GNU CopyLeft (read the
  61. GNU.DOC file included in this distribution).  In particular the sort
  62. module (sort.c std.h) are under both GNU CopyLeft and individual
  63. Copyright.  If you need to be rid of CopyLeft to use this utility you
  64. will have to roll your own (or obtain another public domain) sort
  65. engine.
  66.  
  67. If you do use this and then make changes, bug fixes, or better still,
  68. add a new language parser (PASCAL, FORTRAN, BASIC come to mind right
  69. off the top) or create a macro for a particular editor to deal with
  70. tag files, then please route these changes to me and I will
  71. incorporate these changes and repost the package.
  72.  
  73. The intent of this utility and the release of its source to the
  74. Public Domain is in the interest of high quality programming and code
  75. generation.  Quality is designed in at the earliest stages and must
  76. be maintained by the use of high quality development and maintenance
  77. tools.  If professionals doing good work devote some talent and time
  78. to projects such as this and other projects then the programming
  79. community as a whole benefits (enough evangelism).
  80.  
  81.  
  82.                                     jbk
  83.  
  84. ------------------------------------------------------------------------------
  85.  
  86. Authors:
  87.  
  88.     J. Kercheval
  89.         johnk@wrq.com
  90.         [72450,3702]
  91.  
  92.         Overview and Architecture
  93.         C Module:
  94.         ASM Module:
  95.         Shell:
  96.         Arglist:
  97.         *IX wildcard:
  98.         Match:
  99.         Flags:
  100.         Tag IO (Format, styles and merge):
  101.         Modifications to Sort module to allow use as separate module
  102.             and some subtle bug fixes.  Context diff in SORTMISC.ZIP
  103.         Epsilon extensions:
  104.  
  105.     Mike Haertel
  106.         Free Software Foundation
  107.  
  108.         Original Sort Module:
  109.  
  110.  
  111.     Kevin Dean
  112.         Fairview Mall P.O. Box 55074
  113.         1800 Sheppard Avenue East
  114.         Willowdale, Ontario
  115.         CANADA    M2J 5B9
  116.  
  117.         CRC Validation Module:
  118.  
  119.  
  120. Contributors:
  121.  
  122.     Leonid Kokin
  123.         leok@wrq.com
  124.  
  125.         Brief macro:
  126.  
  127.  
  128. Thanks:
  129.  
  130.     Shane Hartman
  131.         ksh@ai.mit.edu
  132.     Eric Halpern
  133.         erich@wrq.com
  134.     Tad Marshall
  135.         tad@wrq.com
  136.  
  137.         Beta testing and usability editing for distribution
  138.  
  139. ------------------------------------------------------------------------------
  140.  
  141. Program Description:
  142.  
  143.     This utility implements a tags generator for assembly and C code.
  144. This module has been written for and is designed around the 80x86
  145. platform but is written with platform specific code as isolated as
  146. possible.
  147.  
  148.     Tags are informative lines stored (usually) within an ascii file
  149. and specify three things.  First a tag contains a token or an
  150. identifier which is a definition or declaration within the source
  151. code, second a tag contains the file name where that particular token
  152. is defined and third a typical tag will have an offset into the file
  153. where the token is defined (for example a character offset or a line
  154. number).  Occasionally a tag will be generated for an environment
  155. which likes the actual line which is the definition (GNU Emacs for
  156. example) specified instead of a file offset. This type of tag is
  157. sometimes used and is supported by this generator since, while it is
  158. possible for more than one line in a file to be the same and be VERY
  159. different in context, it has an advantage in that if your source
  160. module changes, the tag will probably still be found.
  161.  
  162.     The resulting tag file is intended to be used by an extensible
  163. editor or browser to traverse (possibly) widely placed code during
  164. planning, creation, maintenance and modification of medium and large
  165. projects.
  166.  
  167.     The tags file is used as an index into source definitions.  The
  168. typical implementation allows the user to place the cursor on the
  169. token to be found, start a macro (usually bound to a key) and have
  170. the editor place the cursor at the location which that token is
  171. defined.  This makes code traversal very simple.  If in addition, the
  172. macro implements a history, then moving around code becomes very
  173. similar to using a hypertext system.
  174.  
  175.     This generator has been designed to be used within a project make
  176. file and has a large number of options designed to make the task of
  177. generating and maintaining a tags file as simple and fast as
  178. possible.  There are three good methods for generating tags out of a
  179. makefile and each method is best for particular situations.  The
  180. examples below use OPUS make scripts as makefile code samples.
  181.  
  182.     1)  The first method is to generate a new tag file every time the
  183.         executable is generated.  This method is the simplest to
  184.         implement and is good for small and very small projects.
  185.  
  186.         This would be accomplished with either a list file or a macro
  187.         within the makefile.  For example:
  188.  
  189.             MYEXE: tags
  190.  
  191.             TAGS:
  192.                 tags -tdefault.tag $(TAGFLAGS) $(SRCS)
  193.  
  194.         or
  195.  
  196.             MYEXE: tags
  197.  
  198.             TAGS:
  199.                 tags -tdefault.tag $(TAGFLAGS) @project.lst
  200.  
  201.         This would result in all source files in the project being
  202.         tagged every time the executable was generated.
  203.  
  204.  
  205.     2)  The second method is to generate the new tag list for every
  206.         file that is processed at the time that it is processed.
  207.         This method has an advantage in that it will only update
  208.         those files which have changed at each invocation of make and
  209.         it will update every file at the time it successfully
  210.         compiles.  Disadvantages which become a real problem for
  211.         medium to large projects is that targets may share include
  212.         files and thus these include files would be parsed several
  213.         times and there is large overhead when merging the new tags
  214.         into the old tag file which is incurred for every target file
  215.         rather than just once at the end of the make.  An example of
  216.         the way to implement this method in the makefile is given
  217.         below:
  218.  
  219.             .c.obj
  220.                 $(CC) $(CFLAGS) -o $@
  221.                 @echo $< > file.lst
  222.                 !for filename in $**
  223.                     @echo $(filename) >> file.lst
  224.                 !end
  225.                 tags -tdefault.tag $(TAGFLAGS) @file.lst
  226.  
  227.  
  228.     3)  The third is to accumulate filenames within a temporary
  229.         file and to use that file as a LISTFILE on the tags command
  230.         line and to execute the tags executable when the project
  231.         executable in linked.  This method is very good overall
  232.         because no file will be tagged until the end of the make
  233.         (which means you do not have calling and merging overhead to
  234.         worry about) and no file is tagged more than once during a
  235.         make.  This method will also be the fastest over time because
  236.         of the incremental nature of the tagging (notice that the
  237.         list file is deleted after tags is run so that files are
  238.         accumulated until the make succeeds and is then purged for
  239.         the next source change and make cycle).  This method suffers
  240.         in that tags are not generated until a successful make has
  241.         occurred and causes problems when large changes are underway
  242.         (this is usually not a major problem).  An example is given
  243.         below:
  244.  
  245.             .c.obj:
  246.                 $(CC) $(CFLAGS) -o $@
  247.                 @echo $< >> file.lst
  248.                 !for filename in $**
  249.                     @echo $(filename) >> file.lst
  250.                 !end
  251.  
  252.             MYEXE: $(OBJ)
  253.                 $(LINK) $**, $@;
  254.                 tags -tdefault.tag $(TAGFLAGS) @file.lst
  255.                 del file.lst
  256.  
  257.  
  258.     Several make file utilities have feature which make tags a little
  259. easier to implement within the make process and below are suggestions
  260. for optimizing your environment using OPUS make and PolyMake.
  261.  
  262.     1)  Use directives to force your make facility to release as much
  263.         memory as possible for the tags executable.  Tags may take up
  264.         quite a bit of core for large projects during the sort phase.
  265.         Within OPUS make this is accomplished by placing the
  266.         directive after the target and before the colon, for
  267.         instance:
  268.  
  269.             TAGS .MISER: $(SRCS)
  270.                 tags -tdefault.tag $(TAGFLAGS) $**
  271.  
  272.         PolyMake has a separate directive which takes a list of
  273.         executables which are to be given more memory, as an example:
  274.  
  275.             .MEMSWAP cl link tags
  276.  
  277.         Doing this will help with tight memory situations.
  278.  
  279.     2)  Use response files to overcome the limitations of the DOS
  280.         command line.  Normally you will want to generate a response
  281.         file manually in the makefile.  An example of doing this is
  282.         shown in the examples above in the sections dealing with
  283.         tagging methods.  Note that you may not place options within
  284.         the response file.  Only comments and filenames are allowed
  285.         within the response files used by this utility.  Manual
  286.         creation of response files are suggested because of the
  287.         additional control allowed over the the files placed in the
  288.         response file.  For example, it is simple to change the
  289.         response file generator to exclude all *.h files (or some
  290.         other file to be filtered) from the response file.
  291.             OPUS make will automatically create response files for
  292.         specified executables and pass a response file on the
  293.         utilities command line after prepending a '@'.  For example,
  294.         the directive below would place all input files into a
  295.         temporary file and passes the command line to the tags
  296.         executable as "tags @mkXXXXXX.rsp".
  297.  
  298.             .RESPONSE_LINK tags
  299.  
  300.         The response file created will contain all the command line
  301.         for that particular utility, so that if you are specifying a
  302.         tag file or detailing tagging or need to use any switches for
  303.         tags then you need to manually generate a response file (this
  304.         is not a major undertaking).
  305.             PolyMake uses a concept called a local input file to
  306.         allow the semi-automatic creation of response files.
  307.  
  308.  
  309.     3)  Use built in dependency macros to create the new file list to
  310.         tag.  In the example above I used the $** macro which expands
  311.         to all dependency files for the current target.  If your
  312.         environment is such that you have generated a complete tag
  313.         file then you could use the dependency macro $? instead of
  314.         $**.  This will create a list of only those dependency files
  315.         which have actually been changed or are newer than the
  316.         target.  This method assumes that you never delete your tag
  317.         file (without generating a new tag file from a batch file or
  318.         by some other equivalent method).  If you did delete your tag
  319.         file then even if you removed all your object files and
  320.         recompiled, you would probably not get all source files
  321.         tagged correctly (especially include files used by only one
  322.         module which have not changed).  Use of the $? macro is not
  323.         recommended unless your development environment is very
  324.         stable or very large.
  325.  
  326.  
  327.     Included in this distribution is EEL code which has been ported
  328. from the parsers in this utility.  This allows those lucky enough to
  329. be using Epsilon as their programmer's editor to generate these tags
  330. from within their primary editing environments (while this is quite a
  331. bit slower, it is also sometimes very convenient).  Epsilon users
  332. have the additional advantage of using the built in tags package
  333. which is shipped with Epsilon and which is directly supported by this
  334. tags generator.
  335.  
  336.     Also included here is a macro set for brief to use the MicroSoft
  337. Error format tags generated by this utility.  While it is a poor
  338. substitution for built in support, it is a good example of reasonable
  339. ways to do this for extensible editors.
  340.  
  341.     One nice thing which falls out of this code is a very well done
  342. sort routine which is UNIX compatible, highly portable and one of the
  343. fastest I have seen (UNIX, VMS, Ultrix, MSDOS, etc.).  This utility
  344. is automatically made if you make the tags generator or build using
  345. the included makefile.
  346.  
  347. ------------------------------------------------------------------------------
  348.  
  349. Usage: TAGS {[OPTIONS] [FILENAME]}
  350.  
  351. Options Syntax:
  352.  
  353.     -h
  354.  
  355.         Obtain a detailed help screen directed to standard output.  In a
  356.         pinch this will do as a manual if redirected to a file.
  357.  
  358.     @LISTFILE
  359.  
  360.         Use LISTFILE as a "response" file.  This file is a list of
  361.         input filenames.  This file lists filenames (with or without
  362.         wildcards) one at a time and the filenames may be separated
  363.         by '+', ',', ';' or by whitespace.  In addition, comments are
  364.         allowed within the LISTFILE.  Comments are delimited by
  365.         placing a pound sign '#' before the comment.  This is very
  366.         similar to comments allowed in a makefile except that
  367.         comments are allowed on any line or at the end of any line,
  368.         start at the '#' and go to the end of the current line.
  369.         There must be at least one character between the filename and
  370.         the comment character (ie '+', ',', ';' or whitespace) to
  371.         differentiate between the beginning of comment and a filename
  372.         character (since '#' is a valid element of a filename).
  373.  
  374.  
  375.     -x{EXCLUDEFILE|@LISTFILE}
  376.  
  377.         Excludes the files specified by EXCLUDEFILE or excludes all
  378.         files listed in LISTFILE using the same syntax described
  379.         above.
  380.  
  381.  
  382.     -tTAGFILE
  383.  
  384.         Add new generated tags to TAGFILE.  This file may or may not
  385.         exist.  All tags from TAGFILE which were derived from files
  386.         currently being parsed will be removed during the merge
  387.         phase.  This tagfile is assumed to be in one of this
  388.         utilities output formats.  If sorting is specified then new
  389.         tags will be merged in correct order with current case
  390.         sensitivity, otherwise tags will be placed at the beginning
  391.         of the new resulting tag file (this will result in quicker
  392.         responses during tag searches while editing).  if -m or -s
  393.         are used this switch is ignored (all output is to stdout).
  394.  
  395.  
  396.     -lLOGFILE
  397.  
  398.         Output all activity to LOGFILE.  The log file will be created
  399.         in a LISTFILE format (ie. suitable as input using the
  400.         @LISTFILE syntax).  The behavior regarding existing files is
  401.         determined by the case of the switch as follows:
  402.  
  403.             -l (lower case) creates and outputs to a file overwriting
  404.                any currently existing file
  405.             -L (upper case) appends all output to the logfile if
  406.                there is an already existing file
  407.  
  408.  
  409.     -o[options]
  410.  
  411.         This switch is used to determine the output format to the
  412.         output stream.  [options] may be one of the following:
  413.  
  414.          e  Epsilon tag format
  415.  
  416.             ( tokenString;fileName;characterOffset )
  417.  
  418.             This format is used by the Epsilon editor (V4.x and V5.x)
  419.             created by Lugaru Software and specifies the token
  420.             identifier, the file name (including full path, normally)
  421.             and the character offset of the beginning character
  422.             (starting at character 0).
  423.  
  424.          g  GNU tag format
  425.  
  426.             ( tokenString {tab} fileName {tab} /$line^/ )
  427.  
  428.             This format is used by GNU's EMACS editor, originally
  429.             written by Richard Stallman and widely used in the UNIX
  430.             community.  This is also the format created by its
  431.             companion utility "ctags" which does very simple function
  432.             header tagging.
  433.  
  434.          s  Space-Delimited format
  435.  
  436.             ( tokenString fileName lineNumber )
  437.  
  438.             This format is the simplest format available and requires
  439.             very little parsing and is very simple to import into
  440.             foreign formats (ie. database formats, etc.).
  441.  
  442.          m  MicroSoft Error format
  443.  
  444.             ( tokenString fileName(lineNumber) )
  445.  
  446.             This format has an advantage in that it has been around
  447.             for quite some time and a fair amount of effort has been
  448.             expended to parse this format and move to the location in
  449.             the source specified during compilation stages.  Many
  450.             macros may be modified to use this type of tag format
  451.             with very minor changes.
  452.  
  453.  
  454.     -a[options]
  455.  
  456.         This switch is used to specify the types of tokens for which
  457.         tags are generated for tagging of assembly files.  All token
  458.         types are tagged as the default ( -afdlmsu ).  Source modules
  459.         are expected in 80x86 assembly using MASM/TASM syntax.  The
  460.         location of the -a switch on the command line is important.
  461.         All files (and files found in LISTFILEs) will be tagged using
  462.         assembly tagging (and the options specified on that switch)
  463.         until another -a or -c switch is found.  Order is not
  464.         important for the options to this switch.
  465.  
  466.          f  procedure labels
  467.  
  468.             ( token proc )( proc token )
  469.  
  470.             This is a mnemonic for function (which has nothing to do
  471.             with a procedure call in assembly, but does well for
  472.             frail human memory.  This option specifies tagging of the
  473.             "proc" keyword.
  474.  
  475.          d  definition labels
  476.  
  477.             ( token equ const )( token db declaration )
  478.  
  479.             This option specifies tagging of defines and definition
  480.             labels such as the tokens "equ", "db", "dq", "dw", "df",
  481.             etc.
  482.  
  483.          l  local labels
  484.  
  485.             ( token label )( label token )( token: )
  486.  
  487.             This option specifies tagging of local labels (labels of
  488.             local file duration).  This includes the keyword "label"
  489.             as well as the shorter ':' notation.
  490.  
  491.          m  macro labels
  492.  
  493.             ( token macro )( macro token )
  494.  
  495.             This option specifies tagging of defined macros using the
  496.             keyword "macro".
  497.  
  498.          s  struc labels
  499.  
  500.             ( token struc )( struc token )
  501.  
  502.             This option specifies tagging of structure definitions
  503.             defined using the keyword "struc".
  504.  
  505.          u  union labels
  506.  
  507.             ( token union )( union token )
  508.  
  509.             This option specifies tagging of union definitions
  510.             defined using the keyword "union".
  511.  
  512.  
  513.     -c[options]
  514.  
  515.         This switch is used to detail the token types to tag in C and
  516.         C++ source files.  All token types are tagged by default
  517.         ( -cdmstekuvcfpxi ).  Source files are expected in standard
  518.         ANSI 2.0 C/C++ syntax.  The location of the -c switch on the
  519.         command line is important.  All files (and files found in
  520.         LISTFILEs) will be tagged using C tagging (and the options
  521.         specified on that switch) until another -a or -c switch is
  522.         found.  Order is not important for the options to this
  523.         switch.
  524.  
  525.  
  526.          d  defines
  527.  
  528.             ( #define token statement )
  529.  
  530.             This option specifies that defines are to be tagged
  531.             (preprocessor defines).  This does not include macros
  532.             which are an extended use of the #define preprocessor
  533.             directive.
  534.  
  535.          m  macro labels
  536.  
  537.             ( #define token() statement )
  538.  
  539.             This option specifies tagging of macros defined via use
  540.             of the preprocessor #define directive.
  541.  
  542.          s  struct globals
  543.  
  544.             ( struct token {} )
  545.  
  546.             This option specifies tagging of structures defined via
  547.             use of the "struct" keyword and implicitly defined within
  548.             C++ syntax variations.
  549.  
  550.          t  typedef globals
  551.  
  552.             ( typedef declaration token, token, ... )
  553.  
  554.             This option specifies tagging of identifiers defined via
  555.             use if the "typedef" keyword.
  556.  
  557.          e  enum globals
  558.  
  559.             ( enum token {} )
  560.  
  561.             This option specifies tagging of enumerations defined via
  562.             use of the "enum" keyword.
  563.  
  564.          k  enum konstants
  565.  
  566.             ( enum { token, token, token, ...} )
  567.  
  568.             Note the cute spelling if constants with a 'k' so that I
  569.             can justify the assignment of this letter.  This option
  570.             specifies tagging of enumeration constants within
  571.             declared enumerations.
  572.  
  573.          u  union globals
  574.  
  575.             ( union token {} )
  576.  
  577.             This option specifies tagging of unions defined via use
  578.             of the "union" keyword.
  579.  
  580.          v  global variable
  581.  
  582.             ( declaration token, token = {}, token, ... )
  583.  
  584.             This option specifies tagging of global variable
  585.             declarations.
  586.  
  587.          c  global class
  588.  
  589.             ( class token: {} )
  590.  
  591.             This option specifies tagging of class definitions
  592.             specified via use of the "class" keyword.
  593.  
  594.          f  function definitions
  595.  
  596.             ( token() declaration {} )
  597.  
  598.             This option specifies tagging of function declarations.
  599.  
  600.          p  prototypes
  601.  
  602.             ( token(); )
  603.  
  604.             This option specifies tagging of prototypes.
  605.  
  606.          x  extern defines
  607.  
  608.             ( extern declaration )
  609.  
  610.             This option will specify that tags which have the extern
  611.             storage class are to be output.  The x option is a
  612.             modifier and will only be effective when other options
  613.             are used (ie.  -cpx must be specified to obtain extern
  614.             prototypes, -cx alone yields nothing).  Note also that
  615.             the -cx modifier has no effect for function, define and
  616.             macro tags which are tagged only according only to the f,
  617.             d and m options respectively.  This modifier may be
  618.             placed anywhere within the options list.
  619.  
  620.          i  static declarations
  621.  
  622.             ( static declaration )
  623.  
  624.             This option will specify that tags which have internal
  625.             static storage class are to be output.  The i option is
  626.             a modifier and will only be effective when other options
  627.             are used (ie.  -cvi must be specified to obtain static
  628.             variable declarations, -ci alone yields nothing).  Note
  629.             also that the -ci modifier has no effect for define and
  630.             macro tags which are tagged only according only to the d
  631.             and m options respectively.  This modifier may be placed
  632.             anywhere within the options list.
  633.  
  634.  
  635.     -q
  636.  
  637.         This is the quiet switch and will suppress normal status
  638.         output to stderr and program version information.
  639.  
  640.  
  641.     -r
  642.  
  643.         This switch will suppress the default output of the full file
  644.         path name and will specify the use of relative pathnames in
  645.         the generated output.
  646.  
  647.  
  648.     -n
  649.  
  650.         This switch will suppress sorting of the tag output (Often
  651.         used in conjunction with GNU style tags)
  652.  
  653.  
  654.     -i
  655.  
  656.         This switch specifies the use of a case sensitive sort
  657.         (Normally a case insensitive sort is used).  I know, the
  658.         character 'i' is normally used for switching to a case
  659.         insensitive behavior, things are tough all over, you'll learn
  660.         to live with it.
  661.  
  662.  
  663.     -m
  664.  
  665.         This option specifies a merge sort of the existing files
  666.         which are parsed as a result of the command line.  All of
  667.         these files are assumed to be sorted in the current style.
  668.         Note that this switch results only in the merge of the input
  669.         files (no tagging is done).  Output is to stdout only (-t is
  670.         ignored) when using this switch.
  671.  
  672.  
  673.     -s
  674.  
  675.         This options specifies that all input files are to be sorted
  676.         only.  All files are assumed to be in an unsorted state.
  677.         Note that this switch results only in sorting of the input
  678.         files (no tagging is done).  Output is to stdout only (-t is
  679.         ignored) when using this switch.
  680.  
  681. ------------------------------------------------------------------------------
  682.  
  683. Notes:
  684.  
  685.     The TMP environment variable is used for temporary files.
  686.  
  687.     The default for tags is to use C style tagging, the Epsilon tag
  688. file format, to sort the output before finally placing it in the
  689. output file (or stdout if -t is not used) and to be verbose and log
  690. activity to stderr.
  691.  
  692.       Each file specified on the command line or within a LISTFILE
  693. will be tagged only once regardless of the number of times it appears
  694. on the command line (This includes LISTFILEs as well as filenames and
  695. the files listed within LISTFILEs).
  696.  
  697.       All of the switches may be specified anywhere on the command
  698. line and with the exception of the style switches (-a, -c) are not
  699. position dependent.  The style switches are active only for input
  700. files which fall after them on the command line (or in a LISTFILE
  701. specified after the switch).This allows the specification of
  702. different tagging styles and types on a file by file basis.
  703.  
  704.       Input file specifications allow the use of *IX shell style
  705. expressions.  This allows input filenames such as "*", "*t?*.c" and
  706. "*[e-gxyz]*".  Note that "*" in this case is completely equivalent to
  707. "*.*" in normal DOS usage. The use of "*." will obtain files without
  708. extensions.
  709.  
  710.       This utility performs a CRC validation on itself to prevent
  711. corruption and viral infection from outside influences.  Modification
  712. of this file in any way will result in a failure of the internal CRC
  713. check.  On CRC failure the program will exit with a warning message.
  714.  
  715.  
  716. ------------------------------------------------------------------------------
  717.  
  718. Caveats:
  719.  
  720.     1) Long lines will cause the buffer count output by the epsilon
  721.        tags format to be incorrect for ASM files.  A long line is
  722.        defined as one over 255 characters in length.  Line counts and
  723.        line outputs will maintain correct behavior (ie. effects only
  724.        Epsilon style output).  Long lines may also cause a mistag.
  725.  
  726.     2) Long tokens in excess of 4K in length will cause the buffer
  727.        count in the C token parser to be incorrect.  Line counts and
  728.        line outputs will maintain correct behavior (ie. effects only
  729.        Epsilon style output).  These large tokens may also cause a
  730.        mistag.
  731.  
  732. ------------------------------------------------------------------------------
  733.  
  734. Known Bugs:
  735.  
  736.     1) Use of unbalanced parens in ifdef'd C/C++ code blocks can cause
  737.         problems, some methods are used to deal with but examples like
  738.  
  739.             #ifdef FOO
  740.  
  741.                 StrangeProc();
  742.             } /* end if function declaration */
  743.  
  744.             #else
  745.  
  746.                 ElseStrangeProc();
  747.             } /* end of function declaration */
  748.  
  749.             #endif
  750.  
  751.         would result in a prototype tag of ElseStrangeProc.
  752.  
  753.     2) Use of unbalanced quotes in comments within _asm code blocks could
  754.         cause the parser to miss a close brace.  For instance
  755.  
  756.             _asm {
  757.                 mov ax,cx   ; blah
  758.                 sub ax,1    ; blah, blah
  759.                 call __foo  ; do not put a single quote here '
  760.             }
  761.  
  762.         will result in a miss of the '}' since the parser is expecting a
  763.         token of the form 'c' where c is one of the standard character
  764.         expressions.  As another example
  765.  
  766.             _asm {
  767.                 mov ax,cx   ; blah
  768.                 sub ax,1    ; blah, blah
  769.                 call __foo  ; an unbalanced quote here " will cause chaos
  770.             }
  771.  
  772.         will produce a situation where the parser merrily chugs along until
  773.         it finds another double quote and this will propagate until another
  774.         unbalanced double quote is found.  Both of these cases will most
  775.         likely result in the loss of all tagging information for the current
  776.         file after the point at which the offending code was found.
  777.  
  778. ------------------------------------------------------------------------------
  779.  
  780. Implementation:
  781.  
  782. The file MANIFEST.DOC describes the files in this distribution.
  783.  
  784. This project was developed using the MicroSoft C Compiler V6.00A with
  785. elements compiled previously under TC, TC++ and BC++.  A port to
  786. other compilers should not be difficult.  The sort module has been
  787. compiled using many different UNIX compilers and the code is under
  788. GNU CopyLeft.  All of the other source files and documentation files
  789. are dedicated to the Public Domain.
  790.  
  791. Some things to be aware of:
  792.  
  793.     This module is compiled using the /G2 option.  This means that
  794. only those using AT (80286) and later class machines may use the
  795. executable supplied with this distribution.  For those still
  796. unfortunate enough to be developing on an XT class machine, you will
  797. need to recompile with the /G0 switch enabled.
  798.  
  799.  
  800.     If you are using a MicroSoft compiler previous to V6.00 then you
  801. should remove the /Og (global optimization) switch from the makefile.
  802. The versions of the MicroSoft C compiler before V6.00 occasionally
  803. had problems with code generation when a routine was too large for
  804. global optimization (these sources have several such routines).
  805.  
  806.  
  807. If you port this to another compiler, place the changes in #ifdef'd
  808. code blocks or create a context sensitive diff file and send it on to
  809. me.  I will then incorporate the changes and make sure that these
  810. changes get circulated in a new release.
  811.  
  812.  
  813. Questions?  Comments?  Accolades?  Insults?  Send them to me and I'll
  814. see what I can do.  I hope you find good use for this utility and
  815. code.
  816.  
  817.                                     jbk
  818.